Registering the Project
These steps are done on the editor's admin page, /translate/admin, by an editor admin.
1. Add the project
Click Add project and give it:
- a Name, shown to translators;
- a Slug, the name the app uses for it. It must match the project name the app's build and live preview use.
A new project watches the main branch to start with.
2. Fill in its settings
Click the project to open its panel. Under Settings:
| Setting | What to enter |
|---|---|
| Where the repo lives | GitHub or Gitea, and the repository, e.g. organisation/repo-name. |
| English file | The path of the English file in the repo, e.g. locales/en.json. Several paths, separated by commas, are tried in order. |
| Branch shown first | The branch translators see first when branches disagree on a string, usually the development branch. |
| Live preview address | For each branch, the address where it is deployed, e.g. the preview site and the live site. |
| Publish workflow | The workflow file in the repo that deploys a branch. Setting it gives translators the Publish button. Leave it empty if the app loads its Irish live. |
Use Watch another branch to add more branches, for example a preview branch.
3. Make sure the editor can reach the repo
The editor needs two things for each repository. Both are set up once for the whole organisation, so usually only a new repository needs adding:
- Read access, to read the English file. If the admin page says Can't read the repo, either the repo or file path is wrong, or the editor's access doesn't cover that repository yet.
- Push notifications (a webhook), so pushes sync automatically.
For Publish, the editor also needs permission to start the repository's deploy workflow.
Changing any of these is a server and infrastructure change. The details are in the translations-editor repository's docs/ folder.
4. Sync each branch once
Pushes sync automatically from now on, but each branch needs a first sync:
- On the branch's card, click Sync.
- A dialog lists every string the sync would change, grouped by namespace, with filters for new, changed and removed strings. Changed strings show the old and new English. Nothing is written yet.
- Check it, then click Apply.
5. Check it is ready
The admin page lists every project under Needs setup or Ready. A project that needs setup shows the first thing it is missing:
| Shown | Meaning |
|---|---|
| No repo set | The repo or English file isn't set. |
| Can't read the repo | The editor tried to read the English file and failed. Hover for the exact error. |
| Never synced | A branch has not had its first sync. |
| No live preview | No preview address is set, or the app didn't answer in the preview. |
Check again reads every repo and tries every live preview again after you fix something. A preview that asks to sign in works once you are signed in to that app in the same browser.
Then run the checks at the end of the Checklist.